// Copyright (c) 2010, Anthony Cassidy
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without modification, are 
// permitted provided that the following conditions are met:
// 
//     * Redistributions of source code must retain the above copyright notice, this list 
//         of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright notice, this 
//         list of conditions and the following disclaimer in the documentation and/or 
//         other materials provided with the distribution.
//     * Neither the name of the AntsAdventureGameCreator nor the names of its contributors 
//         may be used to endorse or promote products derived from this software without 
//         specific prior written permission.
// 
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
// SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
// THE POSSIBILITY OF SUCH DAMAGE.
#pragma once

#include <QString>
class XEmitter;
class XReceiver;
class Verbs;
class XVerbs;
class XVerb;
class Verb;

/*!
@class IEventHandlers
<p>
These are the entrypoints that must be defined for every room.
Rooms are declared by using the ROOMDECLARATION()
or ROOMDECLARATION_WITH_CODES() macros.
</p>

<p>
Once a room is declared, the program will not link until all the above methods
are given an implementation.
</p>

<p>
After a room is entered, the event handlers of that roomwill be called
whenever that corresponding event is triggered.

If state is needed to be shared between the methods of a single room
then declaring static variables in the rooms .cpp file might is one method
that can be used. These static variables can be initialized in the OnEnterRoom()
message handler.

If state needs to be shared between rooms, then the ActiveSavedState of the
SavedStateManager should be used as a data store.
</p>
*/
class IEventHandlers
{
public:
    /*!
    Folder must be the name of the physical folder, where the graphics are found.
    Paths are now allowed.
    */
    virtual QString Folder() = 0;

    /*!
    NumberOfResourceRooms should return the number of Extras for the room.
    */
    virtual int NumberOfResourceRooms() = 0;

    /*!
    ResourceRoomAt should be made to return the name of each ResourceRoom. 
    @param[in] index index will always be less than NumberOfResourceRooms.
    */
    virtual QString ResourceRoomAt(int index) = 0;

    /*! 
    OnInitializeRoom is called before the graphics for a room have 
    started to be displayed
    If you want to make any changes to the default state of a room
    then do it here.
    @param[in] roomName The name of the room that is being exited.
    */
    virtual void OnInitializeRoom(QString roomName)=0;

    /*!
    OnEnterRoom is called when the room is entered and is visible.
    At this time the verbs, command line, and inventory list are all not visible.
    OnEnterRoom is meant for cut scenes and other story telling devices.
    <br>
    Commandline type interaction should not be done in OnEnterRoom, 
    and won't work even if you turn all the aforementioned gui elements on.
    One type of interaction that is allowed is DoChoices().
    <br>
    In OnEnterRoom, the animation engine has been started and
    OnEveryFrame is being called during OnEnterRoom.
    <br>
    @param[in] roomName The name of the room that is being exited.
    */
    virtual void OnEnterRoom(QString roomName)=0;

    /*!
    OnExitRoom is called when the is switched to, just before it is entered.
    @param[in] roomName The name of the room that is being exited.
    */
    virtual void OnExitRoom(QString roomName)=0;

    /*!
    OnEveryTick is called every 25th of a second
    */
    virtual void OnEveryTick()=0;

    /*!
    OnCommandLine is called every time the user executes a command during normal interaction.
    OnCommandLine is only ever called for a room after OnEnterRoom has returned.
    @param[in] verb  a number representing one of the PredefinedVerbConstants.
    @param[in] objectA represents the first object in the sentence.
    @param[in] objectB the second object, and is only sent for verbs that use two objects like Use.
    @param[in] x the x coordinate of the mouse when it triggered the command.
    @param[in] y the y coordinate of the mouse when it triggered the command.
    */
    virtual void OnCommandLineExecute(int verb, QString objectA, QString objectB, int x=0, int y=0)=0;

    /*!
    OnDebugMenuExtension allows the user to add custom items
    to the debug menu, and respond to them when they are clicked.
    <br>
    The engine may call this method in two ways:
    <ol>
    <li>
    First, the engine calls it to query how many menu items
    it should add to the debug menu. In this case
    the method will be called with returnNameOnly == true
    It will firstcall with int i=0, then continue calling until
    you either return a blank string, or a string
    of the same value as one sent earlier.
    </li>
    <li>
    Then when the user chooses one of the
    custom menu items, the method
    is called with returnNameOnly ==false
    and the i parameter set to the same value
    that had previously been used to
    obtain the string of the
    menu item the user has just chosen.
    In this case, you are free to perform
    whatever action you desire.
    </li>
    </ol>
    <br>
    These debug menu items are a useful place to
    execute sequences of Verb/Object actions
    to test user actions that would take much
    effort to replicate with the mouse.
    @param[in] i index of the menu item
    @param[in] returnNameOnly This determines whether the method is requesting a menu name (true) or executing that menu item (false);
    */
    virtual QString OnDebugMenuExtension(int i, bool returnNameOnly)=0;

};



